Updating and Rebuilding with ccBuild

Updating and rebuilding a content collection with ccBuild is accomplished from the command line. The command syntax you use to update and rebuild a content collection with ccBuild is similar to the syntax you used to initially create and build your content collection with one or more additional command options appended to it. Remember, the general command line syntax for ccBuild is: ccBuild makefile [options]

The update and rebuild options that are available to you with ccBuild are the following:

Rebuild your content collection completely
Create an update to your original content collection
Create incremental updates to updates
Update the collection directly (do not create an update)

Depending on the location of the makefile you may need to include the path as well as the name of the makefile. Also, depending on the option you choose you may need to include path and name information after the option. The command line syntax is not case-sensitive, and you can use either a "-" or a "/" in front of any given option.

You must enclose all paths that have spaces in the folder or file names within quotes ("), otherwise ccBuild will not execute. For example, c:\program files\Rocket\nxt 4\mymakefile.mak must be within quotes. However, c:\nxtdirectory\makefiles\mymakefile.mak does not need to be within quotes.

Rebuilding Your Collection Completely
(-A or /A)

To completely rebuild your content collection with ccBuild you use the /A option. When you use the /A option, ccBuild deletes the target content collection (NXT file) and rebuilds the same content collection with new content. Your rebuilt collection still has the same name, ID, and title. This new content collection is based on the makefile you reference in the makefile portion of the command line syntax. You cannot "undo" the update after using this option. The following shows a sample command line statement for this option:

ccBuild c:\cnalearn\makefiles\your_makefile.mak /a

After you execute this command, your "updated" content collection has the same name, id, title, etc. as your original content collection, but now contains updated content that matches the current version of the source documents.

If you want to modify the Name, ID, Title, etc. properties/attributes of your content collection you can do this through the makefile. However, in doing this, you will produce a completely new content collection when you run ccBuild and thus do not need the /A option.

Creating Collection Updates
(-U or /U)

The /U option creates an update file (separate from the NXT file) that contains only the documents that have been modified and any changes you have made in the makefile since the last build. An update file is a file you may create and distribute to update the information of your content collection without completely rebuilding your content collection. Generally, update files are smaller, and make good sense when you make small updates to a content collection.

Since an update file contains all documents that you or others have modified since the last build, if you make changes, even very minor changes, to each source document that belongs in your content collection, your update file will contain every document that your content collection contains. Therefore, in this case you may want to use the /A rebuild your content collection.

When you use this option, ccBuild compares the documents and hierarchical structure in the existing content collection (NXT file), file by file, against the source documents and structure listed in the makefile. When there is a difference, ccBuild places the current file/document, and table of contents and index information in the update file and does not modify the original content collection. This allows you to revert back to the original content collection. The combination of the original content collection, or NXT file, and its update files form the "updated content collection." This updated content collection reflects the current contents of the source documents. You can use the Library Manager or Content Network Manager to deploy update files you create with ccBuild.

Naming and Locating Your Update File

You can name and locate the update file anything you want and anywhere on your server. The update file does not need to be in the same folder as the original NXT file. There are different ways that you can use the /U option to name and locate your update file. The following describes those ways.

Using a Makefile Attribute

You can designate the name and location of your update files within your content collection makefile. To do this, add the update-filename attribute to the content-collection element of your makefile, as Figure 1 illustrates. You can use a relative or absolute path and name in this attribute. The default setting for this attribute is "update.upd" without a path. This default value is set in the makefile.dtd. You can override the DTD default setting by adding the update-filename attribute to the makefile. If you do not specify the location (path), but only the name, ccBuild will place the update file in the same directory as your makefile.

Figure 1. Setting the Name and Location of Your Update File in the Makefile

If you want to designate the name and location of your update file in the makefile, then you should use the /U only command line syntax as follows:

ccBuild "c:\...\your_makefile.mak" /u

Using the Command Line

You can also override both the DTD default setting and your makefile attribute setting by placing the name and location information for your update file in the command line syntax.

You can use the following /U <filename> (no path) option to designate a name for the update file from the command line that overrides the makefile and DTD settings. The command line always takes precedence over the makefile for the name and location of your update file. This option places the update file in the directory from which you run the ccBuild command (...\Rocket\NXT 4\Builder\bin is the default ccBuild.exe install directory), and names the update file according to the name you designate on the command line.

ccBuild "c:\...\your_makefile.mak" /u your_update_file.upd

You can also specify both the name and location (path) of the update file by using the following /U <fullpath> command line option. Again, this option supercedes the update-filename information in the makefile. This option places the update file in the location and with the name you specify on the command line. The location, or path, for the update file can be relative or absolute. If you choose to use a relative path structure, the path should be relative to your current command line directory.

ccBuild "c:\...\your_makefile.mak" /u "c:\...\your_update_file.upd"

Creating Incremental Updates of Updates
(-M or /M)

The /M option is the only option that is useless by itself. This option needs to be used in tandem with the /U option. This option enables you to designate the "master" content collection that you want to update.

With just the /U option, ccBuild compares the source documents listed in your makefile to the current content collection documents to generate an update file (technically, you could say that this too is an incremental update). In this case, the "master" content collection is the existing .nxt file. However, if you want to create an update of the updated content collection, or in other words an incremental update, the /U option is insufficient. So, in order to create an update of an update, or an incremental update, you must designate a "master" (hence the "M") content collection. The name (and location) of the last update file follows the /M, and the name and location of the new incremented update file follows the /U, as follows:

ccBuild "c:\...\your_makefile.mak" /m "c:\...\your_update_file.upd" /u your_update_update_file.upd

The order you use the /U and /M does not matter. However, you must include the name and location of the update file that is serving as "master" immediately following the /M option (unlike the /U option that allows you to leave name and location off). Again, all paths can be absolute or relative; relative to your current directory from which you execute ccBuild. And, all options for /U apply here as well.

Updating Your Collection Directly
(Using No Options)

You can also use the ccBuild command without any options to update your content collection. This is the same command that you use when creating a new content collection with ccBuild. Running ccBuild with no options will create a content collection if the content collection does not exist. If the content collection does exist, ccBuild will update the existing content collection (NXT file) directly, without creating an update file (/U) or dumping the old and writing the new (/A). When updating a content collection in this way, ccBuild requires large amounts of RAM, which can cause the build to fail with even minor changes. You can ensure a successful update and build by using the /A or /U options rather than the No Option option. The following is this option's syntax:

ccBuild c:\...\your_makefile.mak

Duplicating a Content Collection

Another method you may choose to use to update your content collection is to create a completely new content collection rather than using the /U or /A options. To do this, you must either modify the ID attribute in your makefile for the new content collection to make it unique, or you must modify the filename attribute by changing the path or name of the file. All other attributes can remain the same. Updating a content collection in this manner enables you to "hot swap" your collections when deploying your updates online.

Online/Offline Issues When Rebuilding

When you update a content collection you may need to take that collection offline to successfully update that collection. The following summarizes when you need to take your collection offline and when you can leave it online to update.

You must take your collection offline when you:

Use the /A option
Use the /U option when the same update file already exists without renaming or relocating the update file differently (this is when you let the DTD or makefile name and locate the update file, and is like using the /A option on an update file)
Use no options to update an existing content collection

You may leave your collection online when you:

Create a new content collection
First use the /U option (you are creating a brand new file)
Use the /U option but rename or relocate the update file (thus, creating a new file or the same file in a different location)
Use the /M /U tandem option and create incremental update files (thus, renaming the new update file with each iteration)

If you do not take your collection offline when you should have, ccBuild will display the error message in Figure 2. This message means that ccBuild could not do what you want it to do because your content collection is still online.

Figure 3. Updating content collection With ccBuild - Online Error